using System.IO;
using lucere.analysis.index;
using lucere.toolkit;

namespace lucere.service.search
{
	/// <summary>
	/// Expert: Maintains caches of term values.
	///<see cref="IFieldCacheSanityChecker"></see>
	/// </summary>
	public interface IFieldCache
	{
		///<summary>
		/// Checks the public cache for an appropriate entry, and if none is
		/// found, reads the terms in <code>field</code> as a single byte and returns an array
		/// of size <code>reader.maxDoc()</code> of the value each document
		/// has in the given field.
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the single byte values.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// @  If any error occurs.
		/// </summary>
		byte[] GetBytes(IIndexReader reader, string field)
	   ;

		///<summary>
		/// Checks the public cache for an appropriate entry, and if none is found,
		/// reads the terms in <code>field</code> as bytes and returns an array of
		/// size <code>reader.maxDoc()</code> of the value each document has in the
		/// given field.
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the bytes.</param>
		/// <param name="parser">Computes byte for string values.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// @  If any error occurs.
		/// </summary>
		byte[] GetBytes(IIndexReader reader, string field, IByteParser parser);

		///<summary>
		/// Checks the public cache for an appropriate entry, and if none is
		/// found, reads the terms in <code>field</code> as shorts and returns an array
		/// of size <code>reader.maxDoc()</code> of the value each document
		/// has in the given field.
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the shorts.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// @  If any error occurs.
		/// </summary>
		short[] GetShorts(IIndexReader reader, string field);

		///<summary>
		/// Checks the public cache for an appropriate entry, and if none is found,
		/// reads the terms in <code>field</code> as shorts and returns an array of
		/// size <code>reader.maxDoc()</code> of the value each document has in the
		/// given field.
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the shorts.</param>
		/// <param name="parser">Computes short for string values.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// @  If any error occurs.
		/// </summary>
		short[] GetShorts(IIndexReader reader, string field, IShortParser parser);

		///<summary>
		/// Checks the public cache for an appropriate entry, and if none is
		/// found, reads the terms in <code>field</code> as integers and returns an array
		/// of size <code>reader.maxDoc()</code> of the value each document
		/// has in the given field.
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the integers.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// @  If any error occurs.
		/// </summary>
		int[] GetInts(IIndexReader reader, string field);

		///<summary>
		/// Checks the public cache for an appropriate entry, and if none is found,
		/// reads the terms in <code>field</code> as integers and returns an array of
		/// size <code>reader.maxDoc()</code> of the value each document has in the
		/// given field.
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the integers.</param>
		/// <param name="parser">Computes integer for string values.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// @  If any error occurs.
		/// </summary>
		int[] GetInts(IIndexReader reader, string field, IIntParser parser);

		///<summary>
		/// Checks the public cache for an appropriate entry, and if
		/// none is found, reads the terms in <code>field</code> as floats and returns an array
		/// of size <code>reader.maxDoc()</code> of the value each document
		/// has in the given field.
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the floats.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// @  If any error occurs.
		/// </summary>
		float[] GetFloats(IIndexReader reader, string field) ;

		///<summary>
		/// Checks the public cache for an appropriate entry, and if
		/// none is found, reads the terms in <code>field</code> as floats and returns an array
		/// of size <code>reader.maxDoc()</code> of the value each document
		/// has in the given field.
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the floats.</param>
		/// <param name="parser">Computes float for string values.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// </summary>
		float[] GetFloats(IIndexReader reader, string field, IFloatParser parser);

		///<summary>
		/// Checks the public cache for an appropriate entry, and if none is
		/// found, reads the terms in <code>field</code> as longs and returns an array
		/// of size <code>reader.maxDoc()</code> of the value each document
		/// has in the given field.
		///
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the longs.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// @throws java.io.IOException If any error occurs.
		/// </summary>
		long[] GetLongs(IIndexReader reader, string field) ;

		///<summary>
		/// Checks the public cache for an appropriate entry, and if none is found,
		/// reads the terms in <code>field</code> as longs and returns an array of
		/// size <code>reader.maxDoc()</code> of the value each document has in the
		/// given field.
		///
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the longs.</param>
		/// <param name="parser">Computes integer for string values.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// If any error occurs.
		/// </summary>
		long[] GetLongs(IIndexReader reader, string field, ILongParser parser) ;


		///<summary>
		/// Checks the public cache for an appropriate entry, and if none is
		/// found, reads the terms in <code>field</code> as integers and returns an array
		/// of size <code>reader.maxDoc()</code> of the value each document
		/// has in the given field.
		///
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the doubles.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// If any error occurs.
		/// </summary>
		double[] GetDoubles(IIndexReader reader, string field);

		///<summary>
		/// Checks the public cache for an appropriate entry, and if none is found,
		/// reads the terms in <code>field</code> as doubles and returns an array of
		/// size <code>reader.maxDoc()</code> of the value each document has in the
		/// given field.
		///
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the doubles.</param>
		/// <param name="parser">Computes integer for string values.</param>
		/// <returns> The values in the given field for each document.</returns>
		/// If any error occurs.
		/// </summary>
		double[] GetDoubles(IIndexReader reader, string field, IDoubleParser parser) ;

		///<summary>
		/// Checks the public cache for an appropriate entry, and if none
		/// is found, reads the term values in <code>field</code> and returns an array
		/// of size <code>reader.maxDoc()</code> containing the value each document
		/// has in the given field.
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the strings.</param>
		/// <returns> The values in the given field for each document.</returns>
		///  If any error occurs.
		/// </summary>
		string[] Getstrings(IIndexReader reader, string field) ;

		///<summary>
		/// Checks the public cache for an appropriate entry, and if none
		/// is found reads the term values in <code>field</code> and returns
		/// an array of them in natural order, along with an array telling
		/// which element in the term array each document uses.
		/// <param name="reader">Used to get field values.</param>
		/// <param name="field">Which field contains the strings.</param>
		/// <returns> Array of terms and index into the array for each document.</returns>
		///  If any error occurs.
		/// </summary>
		IStringIndex GetStringIndex(IIndexReader reader, string field);

		///<summary>
		/// EXPERT: Generates an array of CacheEntry objects representing all items 
		/// currently in the FieldCache.
		/// <p>
		/// NOTE: These CacheEntry objects maintain a strong reference to the 
		/// Cached Values.  Maintaining references to a CacheEntry the IIndexReader 
		/// associated with it has garbage collected will prevent the Value itself
		/// from being garbage collected when the Cache drops the WeakRefrence.
		/// </p>
		/// <p>
		/// <b>EXPERIMENTAL API:</b> This API is considered extremely advanced 
		/// and experimental.  It may be removed or altered w/o warning in future 
		/// releases 
		/// of Lucene.
		/// </p>
		/// </summary>
		ICacheEntry[] GetCacheEntries();

		///<summary>
		/// <p>
		/// EXPERT: Instructs the FieldCache to forcibly expunge all entries 
		/// from the underlying caches.  This is intended only to be used for 
		/// test methods as a way to ensure a known base state of the Cache 
		/// (with out needing to rely on GC to free WeakReferences).  
		/// It should not be relied on for "Cache maintenance" in general 
		/// application code.
		/// </p>
		/// <p>
		/// <b>EXPERIMENTAL API:</b> This API is considered extremely advanced 
		/// and experimental.  It may be removed or altered w/o warning in future 
		/// releases 
		/// of Lucene.
		/// </p>
		/// </summary>
		void PurgeAllCaches();

		///<summary>
		/// Expert: drops all cache entries associated with this
		/// reader.  NOTE: this reader must precisely match the
		/// reader that the cache entry is keyed on. If you pass a
		/// top-level reader, it usually will have no effect as
		/// Lucene now caches at the segment reader level.
		/// </summary>
		void Purge(IIndexReader r);

		///<summary>
		/// If non-null, FieldCacheImpl will warn whenever
		/// entries are created that are not sane according to
		/// <see cref="IFieldCacheSanityChecker"/>.
		/// </summary>
		TextWriter InfoStream { get; set; }
	}
}